/*
 * Copyright (C) 2024 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.extensions.appfunctions;

import android.app.Service;
import android.content.Intent;
import android.os.CancellationSignal;
import android.os.IBinder;
import android.os.OutcomeReceiver;

import androidx.annotation.MainThread;
import androidx.annotation.RestrictTo;

import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;

/**
 * Abstract base class to provide app functions to the system.
 *
 * <p>Include the following in the manifest:
 *
 * <pre>
 * {@literal
 * <service android:name=".YourService"
 *       android:permission="android.permission.BIND_APP_FUNCTION_SERVICE">
 *    <intent-filter>
 *      <action android:name="android.app.appfunctions.AppFunctionService" />
 *    </intent-filter>
 * </service>
 * }
 * </pre>
 *
 * @see AppFunctionManager
 */
@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
public abstract class AppFunctionService extends Service {
    /**
     * The permission to only allow system access to the functions through the system.
     */
    @NonNull
    public static final String BIND_APP_FUNCTION_SERVICE =
            "android.permission.BIND_APP_FUNCTION_SERVICE";

    /**
     * The {@link Intent} that must be declared as handled by the service. To be supported, the
     * service must also require the {@link #BIND_APP_FUNCTION_SERVICE} permission so that other
     * applications can not abuse it.
     */
    @NonNull
    public static final String SERVICE_INTERFACE = "android.app.appfunctions.AppFunctionService";

    @NonNull
    @Override
    public final IBinder onBind(@Nullable Intent intent) {
        throw new RuntimeException("Stub!");
    }

    /**
     * Called by the system to execute a specific app function.
     *
     * <p>This method is the entry point for handling all app function requests in an app. When the
     * system needs your AppFunctionService to perform a function, it will invoke this method.
     *
     * <p>Each function you've registered is identified by a unique identifier. This identifier
     * doesn't need to be globally unique, but it must be unique within your app. For example, a
     * function to order food could be identified as "orderFood". In most cases, this identifier is
     * automatically generated by the AppFunctions SDK.
     *
     * <p>You can determine which function to execute by calling {@link
     * ExecuteAppFunctionRequest#getFunctionIdentifier()}. This allows your service to route the
     * incoming request to the appropriate logic for handling the specific function.
     *
     * <p>This method is always triggered in the main thread. You should run heavy tasks on a worker
     * thread and dispatch the result with the given callback. You should always report back the
     * result using the callback, no matter if the execution was successful or not.
     *
     * <p>This method also accepts a {@link CancellationSignal} that the app should listen to cancel
     * the execution of function if requested by the system.
     *
     * @param request            The function execution request.
     * @param callingPackage     The package name of the app that is requesting the execution.
     * @param cancellationSignal A signal to cancel the execution.
     * @param callback           A callback to report back the result or error.
     */
    @MainThread
    public abstract void onExecuteFunction(
            @NonNull ExecuteAppFunctionRequest request,
            @NonNull String callingPackage,
            @NonNull CancellationSignal cancellationSignal,
            @NonNull OutcomeReceiver<ExecuteAppFunctionResponse, AppFunctionException> callback);
}
